.so ../bk-macros
.TH "bk diffs" "\*[BKVER]" %E% "\*(BC" "\*(UM"
.SH NAME
bk diffs \- show differences in revision controlled files
.SH SYNOPSIS
.B bk diffs 
.[ARG] opts
.BKARGS
.SH DESCRIPTION
The 
.B bk diffs
command is typically used to show changes to working files relative to the
previously checked in version.
Unified diffs are produced by default.
.LP
The 
.B bk diffs
command supports context, unified, procedural, and side-by-side diffs.
All of the above can be optionally annotated with filename,
author, date, and/or revision numbers.
.LP
To view changes you have made to all of the files in the current directory:
.DS
$ bk diffs
.DE
To see the changes for all files in your tree:
.DS
$ bk \-U diffs
.DE
.SH OPTIONS
.TP \-stats-only\ 
.OPTreq \-A bdpru
Align prefix output in a human readable form.
The set of annotations will be followed by a vertical bar and a space
before the data from each line of the file starts.
Each annotation is aligned in a column.
The option argument[s] turn on one
or more annotations as a prefix to each line.
The possible annotations are:
.RS
.TP
.B b
Prefix each line with the basename of the file.
.tp
.B d
Prefix each line with the date of last modification.
.tp
.B p
Prefix each line with pathname of the file relative to the root
of the repository.
.tp
.B r
Prefix each line with the revision of last modification.
.tp
.B u
Prefix each line the name of the user who last modified it.
.RE
.tp
.OPTreq \-a bdpru
Similar to
.Q \-A 
but without the alignment.
.tp
.B \-b
Ignore changes in amount of white space.
.tp
.B \-B
Ignore  changes  that  just  insert or delete blank lines.
.tp
.B \-c
Do old-style context diffs.
.tp
.OPTreq \-d date
Instead of using revision[s] as the versions to diff, use the revision[s]
specified by the date (see
.BR "help bk range" ).
.tp
.B \-f
Normally, bk diffs does not bother to diff against a checked out, read only
file (unless a revision was specified).
This option forces bk diffs to ignore the read only hint and to do the
diff against all specified files.
.tp
.tp
.B \-F regex
Only useful in unified diffs, the given regex will be matched with the
lines before the diff block and, if a match is found, it will be
printed after the '@@' at the start of the diff block. Typically used
to match function declarations.
.tp
.B \-h
Don't print headers.
.tp
.B \-H
Prefix diffs with the checkin comments of that range of revisions.
The comments printed are those associated with the set difference
of the two revisions.
.tp
.OPTreq \-l rev
Show all changes made by the changeset containing rev 
.ARG rev .
This obscure option is useful when there are multiple deltas in the same 
changeset and you aren't sure of the changeset boundaries.
Similar to 
.DS
bk changes -i\*<file\*> -vvr\*<rev\*>
.DE
.tp
.OPTopt \-L url
Show all the changes unique to this repository relative to the (outgoing)
parent or 
.ARG url
if one was specified.
In this context, "changes" means committed, pending, and/or modified files.
Very similar to:
.DS
bk -A diffs -r@`bk repogca [\*<url\*>]`
.DE
.tp
.B \-n
Do RCS style diffs.
.tp
.B \--normal
Instead of unified diffs (the default) print less verbose diffs like those
produced by diff(1).
.tp
.B \-N
If a specified file is not under revision control treat it as if it were under
revision control and the previous checked in version was empty.
Without this option specified files not under revision control are listed
as \*(lqNew file: \*<filename\*>\*(rq.
.tp
.B \-p
Procedural diffs, like
.QR "diff \-p" .
.tp
.OPTreq \-r rev
Diff revision 
.ARG rev .
(Or key or changeset revision. See 
.B bk help terms
under \*(lqrev argument.\*(rq)
.tp
.OPTreq \-R rev
Show diffs between parent of 
.ARG rev
and
.ARG rev .
If no revision is specified and the files are listed on standard input
as
.ARGc file
.OPTreq | rev
then the revision is taken from the standard input.
.tp
.B \-s
Display side-by-side diffs.  The total width is controlled by
the COLUMNS environment variable, and defaults to 80.
.tp
.B \-\-stats
Print a statistics header like diffstat in addition to the normal diff output.
.tp
.B \-\-stats\-only
Print a statistics header like diffstat and suppress the normal diff
output.
.tp
.B \-S
.tp
.B \-\-standalone
Use with -L in a nested component when you want the component to act like
a standalone repository.
.tp
.OPTreq \-u context
Print unified diffs (this is the default). Optionally, pass the number
of lines of context to print.
.tp
.B \-v
Be verbose about non-matching ranges.
.tp
.B \-w
Ignore white space when comparing lines.
.SH EXAMPLES
You may diff specific revisions:
.DS
$ bk diffs -r1.2..1.4 foo.c
.DE
When only one revision is supplied with
.QR \-r ,
then that revision is
compared to the working file or the top of trunk if the file is not
edited.
.LP
A fairly useful thing is to show the differences introduced by a 
specific revision or changeset:
.DS
bk diffs -R1.5 foo.c
.DE
Normally, the revisions specified mean the revision in the file.
Changeset revisions do not match file revisions and sometimes you
want to see the changes for a specific changeset.  Both of these
accomplish that:
.DS
bk diffs -l@\*<alpha1\*> \*<file\*>
bk changes -i\*<file\*> -vvr\*<alpha1\*>
.DE
To create a patch which captures all content changes as well as all new files:
.DS
bk -Axc diffs -N
.DE
You can use bk diffs to diff your entire tree, including edits against an
existing changeset revision or tag in your repository.  
.DS
$ bk -A diffs 
$ bk -A diffs -r@\*<rev\*>
.DE
To see the diffs in the local tree from the new baseline cset in the parent
(-L changes the diffs behavior to look at the whole tree):
.DS
$ bk diffs -L
.DE
.SH BUGS
This command does not currently handle displaying differences for binary files.
.SH SEE ALSO
.SA changes
.SA diff
.SA difftool
.SA export
.SA range
.br
.\" help://differences
.\" help://sdiffs
.SH CATEGORY
.B Common
.br
.B File
